/**
 * FrameAnimation 类型定义
 *
 * 这个模块定义了帧动画系统的所有 TypeScript 类型
 */

import { ReactNode } from 'react';

/**
 * 时序模式
 * - interval: 使用 setInterval，性能较好，适合大多数场景
 * - raf: 使用 requestAnimationFrame，更精确，适合高精度动画
 */
export type TimingMode = 'interval' | 'raf';

/**
 * 帧动画控制器属性
 */
export interface FrameAnimationControllerProps {
  /** 总帧数（必填） */
  frameCount: number;

  /** 每帧持续时间（毫秒），默认 200 */
  frameDuration?: number;

  /** 是否自动播放，默认 false */
  autoPlay?: boolean;

  /** 是否循环播放，默认 true */
  loop?: boolean;

  /** 初始帧索引，默认 0 */
  initialFrame?: number;

  /** 是否启用平滑过渡（使用 LayoutAnimation），默认 false */
  smoothTransition?: boolean;

  /** 平滑过渡动画时长（毫秒），默认为 frameDuration * 0.8 */
  transitionDuration?: number;

  /**
   * 时序模式，默认 'interval'
   * - interval: 适合慢速动画，省电
   * - raf: 适合快速精确动画
   */
  timingMode?: TimingMode;

  /** 帧变化回调 */
  onFrameChange?: (frameIndex: number) => void;

  /** 播放结束回调（仅在非循环模式下触发） */
  onPlayEnd?: () => void;

  /** 播放开始回调 */
  onPlayStart?: () => void;

  /** 暂停回调 */
  onPause?: () => void;

  /**
   * 渲染函数（Render Props 模式）
   * @param frameIndex 当前帧索引（0 到 frameCount-1）
   */
  children: (frameIndex: number) => ReactNode;
}

/**
 * 帧动画控制器命令式控制接口
 * 通过 ref 调用这些方法来控制动画
 */
export interface FrameAnimationControllerRef {
  /** 开始播放 */
  play: () => void;

  /** 暂停播放 */
  pause: () => void;

  /** 停止播放并重置到初始帧 */
  stop: () => void;

  /** 切换播放/暂停状态 */
  toggle: () => void;

  /** 跳转到指定帧 */
  goToFrame: (frameIndex: number) => void;

  /** 跳到下一帧 */
  nextFrame: () => void;

  /** 跳到上一帧 */
  prevFrame: () => void;

  /** 获取当前帧索引 */
  getCurrentFrame: () => number;

  /** 获取播放状态 */
  isPlaying: () => boolean;

  /** 动态设置每帧持续时间 */
  setFrameDuration: (duration: number) => void;

  /** 动态设置是否循环 */
  setLoop: (loop: boolean) => void;
}
